Inside Macintosh: QuickDraw GX Graphics /

Chapter 6 - Picture Shapes / Picture Shapes Reference

Functions / Hit-Testing Pictures

GXHitTestPicture

You can use the GXHitTestPicture function to determine whether a test point hits a picture shape and to discover which shape in the picture hierarchy is hit.

gxShape GXHitTestPicture(gxShape target, const gxPoint *test,
                         gxHitTestInfo *result, long level, 
                         long depth);

target

A reference to the picture shape to hit-test.

test

A pointer to a gxPoint structure. The GXHitTestPicture function determines whether the location specified by this point hits the target picture.

result

A pointer to a gxHitTestInfo structure. On return, this structure contains information identifying the part of the target picture that was hit by the test point.

level

A level in the picture hierarchy. This parameter, along with the depth parameter, is used to determine which shape in the picture to return as the function result. You must provide a nonnegative value for this parameter. A value of 0 indicates you want the item at the lowest level of the hierarchy.

depth

A shape depth in the picture as drawn. This parameter, along with the level parameter, is used to determine which shape in the picture to return as the function result. You must provide a nonnegative value for this parameter. A value of 0 indicates you want the hit item at the lowest depth.

function result

A reference to the shape (at the specified shape depth and hierarchy level)
hit by the test point. The function result is nil if no shape was hit that satisfies the criteria.

DESCRIPTION

The GXHitTestPicture function compares the point indicated by the test parameter with each shape in the picture referenced by the target parameter. To determine whether the test point hits a shape, this function uses the hit-test parameters contained in that shape's transform object, or contained in the overriding transform if there is one.

If the target picture contains shapes that overlap when drawn, more than one shape might be hit by the test point. The function uses the depth parameter to select which of these shapes is the hit shape. If you set this parameter to 1, the function selects the frontmost shape as the hit shape. If you set this parameter to 2, the function selects the shape immediately behind the frontmost shape as the hit shape, and so on.

Before returning a reference to the hit shape, this function examines how deep into the target picture's hierarcy the hit shape is. If the hit shape is deeper into the hierarchy than the level indicated by the level parameter, this function does not return a reference to the hit shape. Instead, it returns a reference to the subpicture at the appropriate level of the target picture's hierarchy that contains the hit shape.

For example, if the hit shape is at level 2 of the picture hierarchy--that is, it is an item of a picture which is an item of the target picture--then specifying a value of 2 for the level parameter causes the function to return a reference to the shape as the function result. However, if you specify a value of 1 for the level parameter, the function returns a reference to the picture that contains the hit shape, rather than a reference to the hit shape itself. Specifying a level of 0 indicates you want the item at the lowest level of the picture hierarchy.

This function also returns information in the gxHitTestInfo structure pointed to by the result parameter:

• The what field indicates which shape part of the hit shape was hit by the test point.
• The index field indicates the index of the geometric point hit by the test point.
• The distance field indicates the distance of the test point from the shape part hit.
• The which field contains a reference to the hit shape.
• The containerPicture field contains a reference to the picture that contains the hit shape.
• The containerIndex field indicates the index of the hit shape within the container picture.
• The totalIndex field indicates the overall index of the hit shape within the target picture.

For more information about the gxHitTestInfo structure, see the chapter "Transform Objects" in Inside Macintosh: QuickDraw GX Objects.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
parameter_is_nil
parameter_out_of_range	(debugging version)
parameter_out_of_range
Warnings
character_substitution_took_place
font_substitution_took_place
picture_expected	(debugging version)
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)

SEE ALSO

For more information about hit-testing shapes, see the chapters "Shape Objects" and "Transform Objects" in Inside Macintosh: QuickDraw GX Objects.

For examples using this function, see "About Hit-Testing Picture Shapes" beginning on page 6-24.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help